The VideoToolbox is a collection of nearly two hundred C subroutines and several demo and utility programs that I and others have written to do visual psychophysics with Macintosh computers. It's free and may not be sold without permission. It should be useful to anyone who wants to present accurately specified visual stimuli or use the Mac for psychometric experiments. The text file “Video synch” discusses all the ways of synchronizing programs to video displays and the many pitfalls to avoid. The TimeVideo application checks out the timing of all video devices in anticipation of their use in critical real-time applications, e.g. movies or lookup table animation. Low-level routines control video timing and lookup tables, display real-time movies, and implement the luminance-control algorithms suggested by Pelli and Zhang (1991). High-level routines help analyze psychophysical experiments (e.g. graphing or maximum-likelihood fitting of psychometric data). This collection has been continually updated since 1991. Many colleagues have indicated that they are using the software in their labs. Documentation is in the source files themselves. Most of the routines are Mac-specific, but some very useful routines, e.g. the luminance-control, statistics, and maximum-likelihood fitting algorithms, could easily be ported to other computers. Those wishing to acknowledge use of the VideoToolbox software might cite:
Pelli, D. G. and Zhang, L. (1991) Accurate control of contrast on microcomputer displays. Vision Research, 31, 1337-1350. Reprints are available.
AVAILABILITY:
The VideoToolbox software is continually updated. To get the latest version, just send me your mailing address, and I’ll mail you a disk. Or download “VideoToolbox.sea” (a self-extracting archive) electronically from the Info-Mac or MacPsych archives. The ftp servers are called sumex-aim.stanford.edu [36.44.0.6] (look in info-mac/source/c) and ftp.stolaf.edu [130.71.128.9] (look in the pub/macpsych directory). Log in as "anonymous"; any password will do. The gopher servers are called Info-Mac Archives (look in info-mac/source) and St. Olaf University (look in Network Resources/St. Olaf Mailing Lists/MacPsych). To use the email file servers send a query to Info-Mac-Request@sumex-aim.stanford.edu or macpsych-request@stolaf.edu.
The ISR Video Attenuator is a commercial product. Ordering instructions are in the “Video Attenuator” file. I have no financial involvement in the ISR Video Attenuator.
GETTING STARTED:
Try the demos: Sandstorm, Grating, FlickeringGrating, Filter, and TimeVideo. TimeVideo times all of your displays, telling you how quickly you can show movies and do lookup table animation. Read “Video synch”.
Put the VideoToolbox folder anywhere on your hard disk. The key header files: VideoToolbox.h, Luminance.h, and mc68881.h, should be in your THINK C folder (or any subfolder within it), so that THINK C can find them. The simplest way to achieve that is to place the entire VideoToolbox inside your THINK C folder. Instead of copying source files to your projects, just “Add” them using the THINK C Source menu. That will make it easy to update the VideoToolbox.
All the programs that do accurate luminance control use the monitor-calibration data stored in LuminanceRecord1.h or LuminanceRecord2.h (the number is a screen number, similar--but not identical--to the number that appears in the Monitors control panel). These calibration files describe my monitors (Apple High-Resolution Monochrome), and, naturally, before doing any serious data collection you should replace these files with ones that describe your own monitors. Use the CalibrateLuminance program. You’ll need a photometer.
NUMERICAL RECIPES IN C:
A few programs in the VideoToolbox (CalibrateLuminance.c, PsychometricFit.c, and Quick3) use the (very handy) Numerical Recipes software and book. Required changes to these routines (bug fixes) are described in the “Improve Numerical Recipes” document in the Notes folder. I have included pre-compiled CalibrateLuminance and Quick3 applications for users that don’t have the Numerical Recipes.
Numerical Recipes C Diskette for Macintosh $32.50
Numerical Recipes in C: The Art of Scientific Computing $47.50
from:
Cambridge University Press
Orders Department
110 Midland Avenue
Port Chester, NY 10573
1-(800)-227-0247
COMPUTER COMPATIBILITY:
Several colleagues have expressed interest in using this software on PCs and Suns. Most of the routines are built upon QuickDraw, and therefore are only useful on Macs. However, several useful packages use nothing but standard C and could be easily ported to other computers: Quick3 (LogLikelihood.c, MonotonicFit.c, PsychometricFit.c, etc.), ReadAssignments.c, VLambda.c, and all the statistical routines (randU.c, nrand.c, Binomial.c, ChiSquare.c, Mean.c, Normal.c, Shuffle.c, Uniform.c). The luminance-control software in Luminance.c makes minimal use of GDHandles to designate particular video devices and load their cluts, and could be easily converted to work with some other scheme for designating video devices and loading their cluts.
All demos check for any needed facilities (e.g. fpu or color quickdraw). Everything has been thoroughly tested on the Mac II and IIci. Less exhaustive tests have been made on the Mac IIsi, IIfx, II with a Radius Rocket, Quadra 950, and PowerBooks 160 and 170. I expect everything to be compatible with the Mac LC, using the built-in video. The routines that don’t require Color QuickDraw have also been tested on the Mac Portable.
COMPILER COMPATIBILITY:
I recommend that you use the latest version of THINK C, currently 5.04. I suggest you get as much help as you can from the compiler, by always enabling THINK C’s “Require prototypes” and “Check pointer types” options (under “Language Settings”) and “\p is unsigned char *” (under “Compiler settings”). I also recommend using THINK C's universal floating point format (i.e. don't check ?? under “Compiler settings”), because it allows all your projects, whether or not they use the 68881, to use the same ANSI library and precompiled header, and the speed and space penalty is very small.
All the programs in the VideoToolbox are compatible with THINK C 5.04, but, with only three exceptions (SetEntriesQuickly.c, kbhit.c, and CopyBitsQuickly.c) do not use any features unique to the THINK compiler. SetEntriesQuickly.c and kbhit.c require THINK C. CopyBitsQuickly.c generates slower code when compiled by MPW C than when compiled by THINK C.
The Symantec THINK C and Apple MPW C compilers have two important differences.
1. THINK C has a unique scheme for including assembly code in the middle of a C program. (Unfortunately, ANSI C does not specify a standard way to do this.) MPW will only allow machine code (i.e. numbers). This affects CopyBitsQuickly and SetEntriesQuickly. CopyBitsQuickly does compile under MPW C, but won’t be quite as fast.
2. By default, MPW treats “int” as long, whereas THINK treats “int” as short. (It’s a compile-time option.) When it matters, you should explicitly declare your variables as “short” or “long” rather than just “int”.
SYSTEM COMPATIBILITY:
In general, I recommend using the latest System software, currently System 7.1. Everything runs fine under Systems 6 and 7, and is compatible with 32-bit mode and virtual memory. None of these programs are “MultiFinder friendly”. They’re compatible with MultiFinder, but they all hog the machine, which I think is perfectly proper for experiments. (It would be easy to make the programs polite, if you want to do that, by following Apple’s guidelines for using WaitNextEvent() in the New Inside Macintosh: Memory book)
VIDEO CARD COMPATIBILITY:
All video cards that plug into the Mac come with video drivers that conform sufficiently well to the Apple guidelines that they are compatible with the VideoToolbox, but they may be much slower than you'd guess. This is discussed in a separate file, “Video synch”. You should check out your video drivers by running the self-explanatory demo TimeVideo. (You may also want to try the more arcane demo TestGDVideo, which assumes a knowledge of Apple's Designing Cards and Drivers book.)
CONTENTS OF THE VIDEOTOOLBOX DISK:
•Read me—this file.
•Changes—chronological list of additions and bug fixes.
•Advice—list of books & software to help in programming vision experiments.
•Video synch-explains how to synchronize a program to a video card.
•Video Attenuator—ordering and installation instructions.
•VideoToolboxSources—a folder containing many useful subroutines. I suggest that you put the entire VideoToolbox folder inside your THINK C folder. (Or at least put the VideoToolboxSources folder there.) That will make it easier for your projects to access these routines without having to copy the routines into each of your project’s folders. It will also make it much easier to update them, since all your programs will share the same copy.
•Demos—a folder containing a variety of ready-to-run applications demonstrating various features of the toolbox software. Sources are included. I strongly recommend that you run TimeVideo.
•Utilities—a folder containing CalibrateLuminance and other useful ready-to-run projects.
•Notes—improvements to THINK C and Numerical Recipes, documentation for Luminance.c, and explanations of video arcana collected from various sources.
•All Sources.π is a project file that allows your to browse through all the sources in the entire VideoToolbox disk, including demos and utilities. Double click the project to start up THINK C, then double click the name of any source file you want to examine.
CONTENTS OF Utilities FOLDER:
CalibrateLuminance helps you to measure the parameters of your video card, ISR Video Attenuator, and monitor. You will need a photometer. CalibrateLuminance will use a Data Translation FORERUNNER A/D card if you have one. All the results are stored in a “header” file called LuminanceRecord?.h, where ? stands for the screen number. You can then #include this file (at compile time) or ReadLuminanceRecord (at run time) in your programs.
CheckContrast does a rigorous testing of the Pelli & Zhang (1991) algorithms that underlie the ISR Video attenuator and the Luminance.c software. You might find it useful if you want to test your ISR Video Attenuator and Luminance.c.
MeasureMTF measures your video monitor's Modulation Transfer Function, i.e. contrast gain as a function of spatial frequency.
Quick3 is a set of subroutines and a main program to fit psychometric functions. It is described in: Watson, A. B. and Pelli, D. G. (1983) QUEST: a Bayesian adaptive psychometric method. Percept Psychophys, 33 (2), 113-20.
The CricketGraph files are format files that should be moved into the folder in which your CricketGraph application resides. When you start up CricketGraph it will find and load all the format files, so that later, when you want to plot data, these formats will be available in CricketGraph’s Format menu. (Sorry, they don’t work with the new CricketGraph III.)
GetVideoDrivers and GetSlotDrivers copy all drivers into resource files, for subsequent perusal in ResEdit.
CONTENTS OF VideoToolboxSources FOLDER:
Binomial.c, given a binomial sample, returns a confidence interval for the underlying binomial probability.
CardSlot.c finds the first NuBus slot that contains a card of the given name. Returns -1 if there’s no such card.
CenterRectInRect.c, shifts the first rect to center it in the second. OffsetRectTile and RectInRect are trivial but handy routines for playing with rects.
ChiSquare.c, given a sample from a chi square distribution with n degrees of freedom, returns the significance level at which a fit may be rejected.
ConvolveX.c and ConvolveY allow convolution, vertically or horizontally, with an arbitrary one-dimensional point spread function. The source and destination Pixmaps may be the same or different, and may be the screen, so you can watch it happen. Try the demo Filter.
CopyBitsQuickly.c is a dumb substitute for CopyBits that ignores the color tables and palettes, simply copying pixels without any translation. It’s for doing animations. Besides copying images, it can also add or multiply them. At one time it was much faster than CopyBits, but the latest timing (under System 7.01), by TimeVideo, indicates that CopyBits is now nearly as fast as CopyBitsQuickly. Try the demo Sandstorm.
CopyQuickDrawGlobals.c allows THINK C programs to use both the console and MacTraps.
DateString.c creates a unique string representing the date and time, suitable as an extension for a data file name.
DrawPrintf.c does a sprintf and draws the characters into the current port, using the current font etc. Try the demo TestGDVideo.
ffprintf.c prints to two output streams, usually stdout and a file. It also saves and restores the port and GDevice.
FlushCacheRange.c from Apple, provides a machine-independent way of flushing your processor’s instruction and data caches.
GDFrameRate.c measures the frame rate of a video device in Hz. GDFramesPerClutUpdate() measures how long it takes to update the clut, in frames. GDVBLRate() measures the rate of VBL interrupts generated by a video device in Hz. GDMovieSize() measures what fraction of the screen you can fill with a real-time movie (a new image on each frame) using either CopyBitsQuickly or CopyBits to copy from memory to video card. Try the demo TimeVideo.
GDOpenWindow1() opens a full screen color window with an explicit palette on an arbitrary screen . GDDisposeWindow1() to close the window and restore the screen's clut. AddExplicitPalette() adds a palette with all colors marked explicit to any color window, allowing you to use PmForeColor or PmBackColor to designate the number you want to load into the pixmap. Try the demo Grating.
GDVideo.c allows you to control the video driver directly, bypassing QuickDraw. I consider this essential for controlling the lookup table of the video card. GDSetEntries() and GDDirectSetEntries() load the clut, and, as a side effect, may provide a device-independent way to synchronize your experiment to a video card, but run the demo TimeVideo to check out your video cards before you depend on it.
GDGetEntries() reads the clut. (The clut values incorporate any gamma-correction.)
GDRestoreDeviceClut() works in more situations than Apple's RestoreDeviceClut().
GDSaveGamma()/GDRestoreGamma save/restore the driver's gamma-correction table.
GDSetGamma() loads a new gamma-correction table.
GDUncorrectedGamma() loads an identity matrix as the gamma-correction table.
GDGetGamma() gets the currect gamma-correction table, and incidentally, is the only way I know of to determine the number of bits used by the video dac.
GDClutSize() returns the current number of entries in the video driver's clut.
GDName(), GDVersion(), and GDCardName() return the name and version of the video driver and the name of the video card that you’re using.
PatchMacIIciVideoDriver() fixes a bug in the Mac IIci built-in video driver.
Try the demos TimeVideo and TestGDVideo. See “Video synch”.
GetClicks.c waits for a mouse click, and determines whether it’s a single, double, or triple click.
GetScreenDevice.c is a handy way to get the GDHandle of any screen.
GetVoltage.c reads a voltage from the Data Translation Analog to Digital Converter. (This is used heavily by CalibrateLuminance, CheckContrast, and MeasureMTF.)
HideMenuBar.c and SquareCorners(device) allow use of the whole screen. Try Grating.
Identify.c includes several functions, IdentifyCompiler(), IdentifyMachine(), IdentifyVideo(), that produce self explanatory text strings to document test conditions, etc. Try the demos TimeCPU and TimeVideo.
IsNan.c allows you to test whether your double variable contains a Not A Number code instead of a legal number. IsNan() returns the index (1 . . . 255) of the NAN, or zero if it's not a NAN. IsInf() returns -1 for -INF, +1 for +INF, and zero for not ±INF. The extra-fast macro IsFinite() returns 1 if your number is neither NAN nor ±INF.
kbhit.c and getcharUnbuffered() offer old-fashioned microcomputer-style unbuffered access to keystrokes.
Log2L.c quickly returns the (long) integer part of the log2 of a long integer argument.
Luminance.c provides for programming of the lookup table for gamma correction, and use of a video attenuator. Its theory of operation is described by Pelli and Zhang (1991). Documentation is in Luminance.doc in the Notes folder. Try the demos FlickerGrating and Filter.
Luminance.h is the header file for use with Luminance.c.
LuminanceRecord1.h is a sample “header” file produced by CalibrateLuminance.c for one of my monitors. It describes the gamma function and the gains of the three channels of the ISR Video attenuator. You should run CalibrateLuminance to make your own for each of your monitors.
MakeNoise.c synthesizes random checkerboard movies. MakeNoise1 provides a simpler interface that allows you to specify whether or not to randomize phase. Try the demos Sandstorm and NoiseVBL.
MaximizeConsoleHeight.c causes the THINK C console to open to the full height of your main screen.
mc68881.h defines MPW C’s mc68881 and mc68020 preprocessor symbols for THINK C, so your programs can use them in “if” statements without worrying about which compiler you’re using. The symbols are 1 (i.e. true) if the compiled code requires the chip (or better) and 0 otherwise.
Mean.c computes mean (and optionally the standard deviation) of an array of samples (all doubles).
Normal.c computes the probability density, cumulative distribution, and inverse cumulative distribution for the normal distribution.
nrand.c, nrandU(n), and nrandUL(n) return a random number in the range [0,n-1]. The type of the argument and returned value are both short, unsigned short, or unsigned long, respectively.
OpenDataFile.c opens a parameter file for input and a data file for output. Output file name includes a time stamp, making it unique.
PixMapToPostScript.c will convert a grayscale image to a postscript file suitable for printing on a LaserWriter or Linotype.
PlotXY.c is handy for a quick screen plot, especially of incoming data. It plots one point at a time, and does lines, in eight colors, with optional dashing, and optional symbols. Used by MeasureMTF for online display.
PrintfExit.c prints out an error message and exits. Require() tests for any required fpu, cpu, and version of QuickDraw, and notifies the user and exits gracefully if they're absent. All the demos call Require().
QD32Exists.c determines whether 32-bit QuickDraw has been installed. QD8Exists() determines whether color QuickDraw is present. NewPaletteManager() determines whether the new palette manager (documented in Inside Mac volume VI) is present. These routines have no significant advantage over Apple's Gestalt(), which came later.
RandFill.c quickly fills a buffer of any size with random bits. Used by MakeNoise. Try the demos Sandstorm, NoiseVBL, and TimeCPU.
randU.c is a fast 16-bit random number generator. randUL() returns a 32-bit random number. (The ANSI standard rand() provides only 15 bits.)
ReadAssignments.c is a runtime C interpreter that only accepts assignments and comments. Use this in your experiment to interpret a text file containing assignments of experimental parameters that describe your experimental conditions.
ReadLuminanceRecord.c interprets a LuminanceRecord?.h at runtime, as an alternative to using the preprocessor #include mechanism at compile time.
ReadMatLabFile.c allows you to read and write MatLab binary data files. MatLab is a commercial application, sort of like BASIC rewritten by someone who likes linear algebra. ReadMatLabFile.c is based on code written by J.N. Little.
RectToAddress.c returns the memory address of the pixel in a PixMap or BitMap. To my knowledge it will ALWAYS work, dealing correctly with a whole slew of special configurations. Used by CopyBitsQuickly.
RestoreCluts.c restores the Color Lookup Tables of all screens, to clean up when your program is done.
Sane.c has routines, DoubleToExtended() and ExtendedToDouble(), that convert back and forth between 12-byte and 10-byte floating point formats. The only reason for doing this would be to access numerical routines in Apple’s SANE library.
SetEntriesQuickly.c, written primarily by Raynald Comtois, Peter Lennie, and Bill Haake, quickly loads the clut of many popular video cards. Try the demo TimeVideo.
SetFileInfo.c is a handy routine to set the creator and type of a file. The main use for this is to make data files of the correct type so that they can be double clicked and will open directly into the analysis program, typically Excel or Cricket Graph.
SetMouse.c moves the mouse. It complements the Apple-supplied GetMouse(). From THINKin' CaP, 1(2):28-29, Fall 1990.
SetOnePixel.c is obsolete; use SetPixelsQuickly instead, because it's ten times faster. The routines include GetOnePixel(), SetDevicePixel(), GetDevicePixel(), SetPixmapPixel(), GetPixmapPixel().
SetPixelsQuickly.c pokes or peeks a row of pixels, bypassing the color tables. This is the fastest way to get at the pixels in an image, for image processing or synthesis. All the routines work with both bitmaps and pixmaps and any size of pixel:1, 2, 4, 8, 16, or 32 bits. Try the demos Grating and FlickeringGrating.
SetPriority.c and SwapPriority() allow you to set the processor priority in order to prevent interrupts during something that you want to do as fast as possible, e.g. animations. Note that raising the processor priority will temporarily make the mouse and keyboard dead, because they are serviced by interrupts.
Shuffle.c randomly shuffles an array of shorts.
SndPlay1.c plays a sound asynchronously, i.e. it returns immediately, while the sound is still playing.
StringToDate.c reads date such as “6/30/91” and returns secs since 1/1/1904.
Timer.c is an interval timer based on Apple’s Time Manager. StopTimer() returns the time, as a long, in µs that elapsed since calling StartTimer(). StopTimerSecs() returns the elapsed time as a double, in seconds. Try the demos TimeCPU and TimeVideo.
TitleBarHeight.c returns the height of a window’s title bar, in pixels.
TrapAvailable.c, from Apple, determines whether a particular trap is available.
Uniform.c: UniformSample() returns a random sample from the interval [0,1).
VBLInstall.c implements a once-per-video-frame interrupt suitable for use with all video devices. Try the demo TimeVideo.
VideoTFB.c allows direct control of the original Apple color video card, which is no longer sold by Apple but is available for $90 from Shreve Systems (800-227-3971). I wrote it based on my disassembly of the Apple video driver. Don’t use these routines unless you’re prepared to live with the resulting hardware dependency. VideoTFB works with both the "Toby frame buffer card" and the "Mac II High-Resolution Video Card". Try the demos ScrollDemo and TimeVideo.
VideoToolbox.h is the header file that has the prototypes for all the VideoToolbox routines except those in Luminance.c (whose headers are in Luminance.h) and Sane.c.
VLambda.c and VLambdaPrime(double nm) return the photopic and scotopic sensitivity of the standard CIE observer, relative to the peak at 555 or 507 nm. Based on Tables I(3.3.1) and I(4.3.2) in G. Wyszecki and W.S. Stiles (1982) Color Science, 2nd Ed., Wiley, New York.
Zoom.c implements a zoom box, i.e. if you click in the upper right hand corner of your window, in the little box-in-a-box icon, this code will expand the window to fill the screen with which it has the greatest intersection.
SetMouse.c and HideMenuBar.c are copyrighted by SPLASH Resources. Their restrictions are reproduced in those files. FlushCacheRange.c (originally called Cache.c) is copyrighted by Apple Computer Corp.
The compiled applications incorporate code copyrighted by others:
DISCLAIMER (included at the request of the MacPsych archive):
The VideoToolbox is provided “as is” without warranty of any kind. Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, and St. Olaf College make no claims concerning the accuracy or correctness of the computer code contained in, or the results of the use of VideoToolbox. The entire risk as to the results and performance of VideoToolbox is assumed by you. If the VideoToolbox is defective you, and not Denis Pelli, Syracuse University, SCiP, the operators of MacPsych, or St. Olaf College assume the entire cost of all necessary servicing, repair or correction.
